home *** CD-ROM | disk | FTP | other *** search
/ Mac OS 9 Serial Number Archive / SN Archive 2023.11.04.toast / BSNG / SDK / BSNG SDK 1.0.2 / BSNG API.h next >
Encoding:
C/C++ Source or Header  |  1997-10-05  |  9.9 KB  |  180 lines  |  [TEXT/CWIE]
  1. /*
  2.  * $Workfile:: BSNG API.h                                                     $
  3.  * $Revision:: 2                                                              $
  4.  *
  5.  * $Author:: Buck Rogers                                                      $
  6.  * $Modtime:: 05.10.1997 19:10 Uhr                                            $
  7.  *
  8.  * $History:: BSNG API.h                                                      $
  9.  * 
  10.  * *****************  Version 2  *****************
  11.  * User: Buck Rogers  Date: 05.10.1997   Time: 19:12 Uhr
  12.  * Updated in $/BSNG/Plugins/BSNG SDK
  13.  * Added name, company and number of copies items that contain the default
  14.  * values set in the BSNG App preferences
  15.  * 
  16.  * *****************  Version 1  *****************
  17.  * User: Buck Rogers  Date: 30.09.1997   Time: 18:31 Uhr
  18.  * Created in $/BSNG/Plugins/BSNG SDK
  19.  * Adding subproject 'BSNG' to '$/'
  20.  *
  21.  * $NoKeywords::                                                              $
  22.  */
  23.  
  24.  
  25. #pragma once
  26.  
  27.  
  28. #if PRAGMA_ALIGN_SUPPORTED
  29. #pragma options align=mac68k
  30. #endif
  31.  
  32. /*
  33.     These are the IDs of the 10 LGAEditField you can use.
  34.     MAKE SURE THAT EVERY LGAEditField YOU ADD TO YOUR LAYOUT IS WITHIN THAT RANGE!!!
  35.     
  36.     Note:    The only items that need special ID and/or message ranges are:
  37.             LGAEditFields (ID range: between kEditItem1 = 100001 to kEditItem10 = 100010)
  38.             LGAPushButtons (ID and message range: between 300000 and 399999)
  39.     
  40.     Everything else you add, like LGACaptions or LGAFocusBorders should have an ID smaller than 100000 though to
  41.     avoid possible conflicts with the BSNG App in the future.
  42. */
  43.  
  44. enum EditFieldItem        {kEditItem1 = 100001, kEditItem2 = 100002, kEditItem3 = 100003, kEditItem4 = 100004, kEditItem5 = 100005,
  45.                          kEditItem6 = 100006, kEditItem7 = 100007, kEditItem8 = 100008, kEditItem9 = 100009, kEditItem10 = 100010};    
  46.  
  47. /*
  48.     These are values you can use to access the itemValue array. If you want to access the value the user entered in your
  49.     LGAEditField with the ID kEditItem2 you can use itemValue[1] or for more readability itemValue[kItemValue2]
  50. */
  51.  
  52. enum EditFieldValue        {kItemValue1 = 0, kItemValue2 = 1, kItemValue3 = 2, kItemValue4 = 3, kItemValue5 = 4,
  53.                          kItemValue6 = 5, kItemValue7 = 6, kItemValue8 = 7, kItemValue9 = 8, kItemValue10 = 9};
  54.  
  55. /*
  56.     Here are the descriptions of all the possible messages your plugin can recieve:
  57.  
  58.     msgExtInit                 Will be passed when your plugin gets loaded.
  59.                             This is the time to set the 'wantsRandomButton' and 'canAddToSNList' values and to initialize your
  60.                             global variables. You should also load all additional resources (if you use any in your plug) that
  61.                             are needed for your calculations, like CRC tables etc., at this point of time.
  62.                             If your initialisation failed for some reason report that back to the BSNG App by setting 'error'
  63.                             to errExtInitFailed, if your init was successful set 'error' to errExtNoErr
  64.     
  65.     msgExtCalcHit            Will be passed when the user pressed the 'Calculate' button in the BSNG App.
  66.                             You should validate all necessary data for your calculations (passed to you in the 'itemValue' array)
  67.                             before you start calculating. set 'error' to errExtIncorrectValue with the corresponding
  68.                             EditFieldItem in 'errorInItem' back to the BSNG App if the validation failed.
  69.                             If the validation was succesful start your calculation and pass the result back in the appropiate entry
  70.                             in the 'itemValue' array (e.g. use itemValue[kItemValue2] if your output LGAEditField has the ID kEditItem2,
  71.                             use itemValue[kItemValue3] if your output LGAEditField has the ID kEditItem3 etc).
  72.     
  73.     msgExtRandomHit            You will only receive that message if you set 'wantsRandomButton' to true at Init time.
  74.                             Create a random serial number not dependent on user input and fill in all the necessary data into the
  75.                             'itemValue' array to display your calculations (see msgExtCalcHit how to do that)
  76.     
  77.     msgExtItemHit            You will receive that message only when you added one or more LGAPushButtons to your layout.
  78.                             The LGAPushButton IDs and messages have to be between 300000 and 399999 to make this work. The message
  79.                             of the LGAPushButton that was pressed will be passed to you in 'itemMessage'.
  80.                             You can do lots of things with this feature, like display your own about box, play a sound or whatever
  81.                             else comes to your mind. Actually this is very powerful because you get all control you need to
  82.                             'customize' your plugin, but please keep in mind not to 'bloat' your plugin by adding too much fancy stuff.
  83.                             All the values you probably changed for some reason in the 'itemValue' array will be displayed to the user
  84.                             when the BSNG App gets control again. Have fun :-)
  85.                             
  86.     
  87.     msgExtCreateRandom        Your plugin will only get this message if you set 'canAddToSNList' to true at Init time.
  88.                             Use the 'outputRefNum' to write your randomly calculated serial numbers to the filestream.
  89.                             Use FSWrite and/or the helper functions myOutputPStr, myOutputSuffixedPStr, myOutputText
  90.                             and myOutputSuffixedText from "standard utils" (included with this package) to write to the filestream.
  91.                             You should calculate 'numOfListNumbers' random numbers if you can and write them to the stream...
  92.                                 
  93.     msgExtCleanup            Will be passed when your plugin gets unloaded.
  94.                             All memory allocations you made at Init time or whenever and all the resources you loaded should be
  95.                             deallocated/freed/dissposed when your plugin receives this message to avoid memory leaks.
  96. */ 
  97.  
  98.  
  99. enum ExternalMessage    {msgExtInit = 1, msgExtCalcHit = 2, msgExtRandomHit = 3, msgExtItemHit = 4, msgExtCreateRandom = 5, msgExtCleanup = 6};
  100.  
  101. /*
  102.     Here are the descriptions of all supported errors at the moment. If you pass another value back to the BSNG App than those
  103.     listed here the user will be prompted with an 'the plugin reported an unknown error, please continue with caution' alert
  104.     
  105.     errExtInitFailed        Your plugin failed to initialize itself at Init time
  106.     
  107.     errExtIncorrectValue    report that error at msgExtCalcHit if the user entered an incorrect value into one of the LGAEditField.
  108.                             Report the field containing the error back to the BSNG App by setting 'errorInItem' to the
  109.                             corresponding LGAEditField ID (kEditItem1...kEditItem10)
  110.     
  111.     errExtWritingToList        report that error when you got the msgExtCreateRandom message and for one or the other reason can't
  112.                             write your data to the list. If you report that error the creation of the complete list will be aborted.
  113.     
  114.     errExtNoErr                report this if everything works fine :-)
  115. */
  116.  
  117. enum ExternalError        {errExtInitFailed = -100000, errExtIncorrectValue = -100001, errExtWritingToList = -100002, errExtNoErr = 0};
  118.  
  119.  
  120. typedef struct
  121. {
  122.     short                theMessage;                /*    set by the BSNG App, you have to react to these messages */
  123.                                                 /*    (see ExternalMessage above) */
  124.     
  125.     unsigned long        itemMessage;            /*    if you added one or more LGAPushButtons (please only use LGAPushButtons, */
  126.                                                 /*    no other controls are supported yet) to your layout you find the message you */
  127.                                                 /*    configured for that LGAPushButton in here. LGAPushButton IDs and messages MUST be */
  128.                                                 /*    between 300000 and 399999 */
  129.     
  130.     Boolean                wantsRandomButton;        /*    set to true at Init time if your plugin can create random serial numbers */
  131.     
  132.     Boolean                canAddToSNList;            /*    set to true at Init time if your plugin can create numbers for the */
  133.                                                 /*    Random Serial Number List */
  134.     
  135.     Str63                name;                    /*    name, company and numCopies are default values entered in the BSNG App preferences. */
  136.     Str63                company;                /*    if possible copy these in values in the corresponding itemValue items at Init time */
  137.     Str15                numCopies;                /*    so that these values can appear as default in your generator. Also make sure that */
  138.                                                 /*    you make a serial number using these infos when the Serial Number List gets */
  139.                                                 /*    created (of course only if your plugin is a name-based algorithm) */
  140.     
  141.     unsigned short        numOfListNumbers;        /*    how many numbers to create for the random Serial Number List */
  142.     
  143.     short                outputRefNum;            /*    the reference number of the file to write to when we build the */
  144.                                                 /*    random Serial Number List */
  145.     
  146.     long                error;                    /*    if an error occured put the appropiate error number (see 'ExternalError' above) */
  147.                                                 /*    in here */
  148.                                                 
  149.     unsigned long        errorInItem;            /*    if the error that occured is of type 'errExtIncorrectValue' put the
  150.                                                 /*    appropiate 'EditFieldItem' in here. Lets say the wrong value is in itemValue[3] */
  151.                                                 /*    which is equal to itemValue[kItemValue4] put kEditItem4 into this field */
  152.     
  153.     unsigned long        randSeed1;                /*    set by the BSNG App, you can use these two randSeed values to initialize the */
  154.     unsigned long        randSeed2;                /*    Ultra Random Number Generator (source included) or any other Random Number Gen */
  155.     
  156.     unsigned long        appLaunchTime;            /*    set by the BSNG App, the time the BSNG App was launched in Ticks */
  157.     DateTimeRec            appLaunchDate;            /*    set by the BSNG App, the time the BSNG App was launched in a DateTimeRec */
  158.     
  159.     StringPtr            itemValue[10];            /*    You can add up to 10 LGAEditFields to your layout (please only use LGAEditFields, */
  160.                                                 /*    no other TextEdit fields are supported yet). The IDs of your LGAEditField MUST be
  161.                                                 /*    between 100001 and 100010 (kEditItem1...kEditItem10) */
  162. } BSNGParamBlock, *BSNGParamBlockPtr;
  163.  
  164.  
  165. /*
  166.     IMPORTANT!!! additional notes:
  167.     
  168.     You MUST create the following resouces, otherwise your plugin will not work:
  169.     
  170.     'cicn' ID 1000    must contain the icon displayed in the plugin list in the BSNG App
  171.     'STR ' ID 1000    must contain the text displayed under the icon, the max. supported length of this text is 27 characters
  172.     'PPob' ID 1000    must contain the layout displayed on the right side of the serial number generator window when your plugin
  173.                     gets selected. Use Metrowerks Constructor 2.4.2 or better (included in this distribution) to cusomize this view,
  174.                     but keep in mind what I told you about the LGAPushButtons and LGAEditFields earlier in this document.
  175. */
  176.  
  177. #if PRAGMA_ALIGN_SUPPORTED
  178. #pragma options align=reset
  179. #endif
  180.